Feature/add ip restriction middleware by Octo8080X · Pull Request #3035 · denoland/fresh

Octo8080X · 2025-06-14T05:02:28Z

Why was this PR initiated?

I opened an issue and held discussions about officially providing middleware in Fresh by porting middleware from Hono.

#3011

What does this PR do?

I introduced the IP Restriction middleware bundled with Fresh by porting the IP Restriction middleware from Hono.

I appreciate your review.

…ction middleware

…ction tests

…e file naming

iuioiua

First pass

iuioiua · 2025-06-14T07:38:39Z

src/middlewares/ip_restriction.ts

+export type AddressType = "IPv4" | "IPv6";
+
+export type NetAddrInfo = {
+  /**
+   * Transport protocol type
+   */
+  transport?: "tcp" | "udp";
+  /**
+   * Transport port number
+   */
+  port: number;
+  address: string;
+  addressType?: AddressType;
+};
+
+export interface ConnInfo {
+  /**
+   * Remote information
+   */
+  remote: NetAddrInfo;
+}


These types already exist within the Deno runtime API. See https://docs.deno.com/api/deno/network.

iuioiua · 2025-06-14T07:40:16Z

src/middlewares/ip_restriction_test.ts

Each test should be wrapped in a Deno.test() call.

@iuioiua san.

Thanks for your comment!
Sorry if I’m mistaken, but I thought when writing in a BDD style, Deno.test would be replaced by describe. Was I incorrect about that?

https://jsr.io/@std/testing/doc/bdd#:~:text=()%2C%2018)%3B%0A%7D)%3B-,Mixed%20test%20grouping,-Both%20nested%20test

I looked at the other code as well.
I understand now that using Deno.test instead of a BDD style is the standard.
I’ll prepare a fix.

src/middlewares/ip_restriction.ts

iuioiua · 2025-06-14T07:41:53Z

src/middlewares/ip_restriction.ts

There's a lot of IP address logic here that might be valuable in other domains. I recommend creating an issue for the Standard Library for any useful utilities to @std/net.

The part you’re pointing out is indeed a generic utility — in Hono, it’s placed in utils as well.
I’ll go ahead and create an issue for now.

@iuioiua

I have created an issue.Thanks.
denoland/std#6722

Octo8080X · 2025-10-07T14:23:26Z

@iuioiua
Hello.
The processing logic for IP addresses has been refactored and isolated into @std/net.
The middleware has been subsequently reconstructed utilizing this new module. Your review is requested.

iuioiua · 2025-10-14T06:33:39Z

packages/fresh/src/middlewares/ip_restriction.ts

+import type { Middleware } from "./mod.ts";
+import { isIPv4, isIPv6, matchSubnets } from "@std/net/unstable-ip";
+
+export type AddressType = "IPv6" | "IPv4" | "none";


I suggest using Deno.NetworkInterfaceInfo.family instead of this new type.

iuioiua · 2025-10-14T06:38:02Z

packages/fresh/src/middlewares/ip_restriction.ts

+function findType(addr: string): AddressType {
+  if (isIPv4(addr)) {
+    return "IPv4";
+  } else if (isIPv6(addr)) {
+    return "IPv6";
+  }
+  return "none";
+}


See first comment.

Suggested change

function findType(addr: string): AddressType {

if (isIPv4(addr)) {

return "IPv4";

} else if (isIPv6(addr)) {

return "IPv6";

}

return "none";

}

function findType(addr: string): Deno.NetworkInterfaceInfo.family | undefined {

if (isIPv4(addr)) {

return "IPv4";

} else if (isIPv6(addr)) {

return "IPv6";

}

return undefined;

}

iuioiua · 2025-10-14T06:42:24Z

packages/fresh/src/middlewares/ip_restriction.ts

+    headers: {
+      "Content-Type": "text/plain",
+    },


Not needed. The content-type header by default is "text/plain;charset=UTF-8" anyway.

Suggested change

headers: {

"Content-Type": "text/plain",

},

iuioiua · 2025-10-14T06:42:49Z

packages/fresh/src/middlewares/ip_restriction.ts

+export interface IPRestrictionRules {
+  denyList?: string[];
+  allowList?: string[];
+}


This interface and its properties should have JSDocs.

iuioiua · 2025-10-14T06:55:11Z

packages/fresh/src/middlewares/ip_restriction.ts

+    if (!ctx.info.remoteAddr.hostname) {
+      return blockError();
+    }


IIUC, this conditional will never be true because ctx.info.remoteAddr.hostname is always defined.

Suggested change

if (!ctx.info.remoteAddr.hostname) {

return blockError();

}

iuioiua · 2025-10-14T22:07:32Z

packages/fresh/src/middlewares/ip_restriction.ts

+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}))
+ * ```
+ *
+ * @example custom error handling


Nit

Suggested change

* @example custom error handling

* @example Custom error handling

iuioiua · 2025-10-14T22:08:15Z

packages/fresh/src/middlewares/ip_restriction.ts

+ * @example custom error handling
+ * ```ts
+ * const customOnError: IpRestrictionOptions = {
+ *   onError: () => {


I think we should show how the onErrors parameters can be used here.

I've gone ahead and added the usage examples.

iuioiua · 2025-10-14T22:09:10Z

packages/fresh/src/middlewares/ip_restriction.ts

+function buildMatcher(ipList: string[]) {
+  return (addr: string) => {
+    return matchSubnets(addr, ipList);
+  };
+}


Not needed if we go ahead with using matchSubnets inline, as stated below.

Suggested change

function buildMatcher(ipList: string[]) {

return (addr: string) => {

return matchSubnets(addr, ipList);

};

}

iuioiua · 2025-10-14T22:11:11Z

packages/fresh/src/middlewares/ip_restriction.ts

+
+  const denyMatcher = buildMatcher(denyList);
+  const allowMatcher = buildMatcher(allowList);
+


Something like this will avoid the need for if (options?.onError) conditionals and being inline makes the behaviour of onError more immediately understood.

Suggested change

const onError = options?.onError ?? (() =>

new Response("Forbidden", {

status: 403,

headers: {

"Content-Type": "text/plain",

},

}));

I've made the adjustment to make it inline. Thanks!

iuioiua · 2025-10-14T22:13:14Z

packages/fresh/src/middlewares/ip_restriction.ts

+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))
+ * ```
+ */
+export function ipRestriction<State>(


I'm not strongly for or against this name... Are we sure about this name? Any other alternatives?

@iuioiua
How about 'IpRule' or 'IpFilter' instead of 'IP Restriction'? They sound pretty good.

ipFilter sounds okay to me.

…to8080X/fresh into feature/add_ip_restriction_middleware

iuioiua

Getting closer to being ready, IMO. Few nits. HMU on Discord (same username) if you want to chat about any of this.

iuioiua · 2025-10-20T21:29:25Z

packages/fresh/src/middlewares/ip_restriction.ts

+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))
+ * ```
+ */
+export function ipRestriction<State>(


ipFilter sounds okay to me.

iuioiua · 2025-10-20T21:31:19Z

packages/fresh/src/middlewares/ip_restriction.ts

+    }
+
+    if (matchSubnets(addr, rules.allowList || [])) {
+      const res = await ctx.next();


Suggested change

const res = await ctx.next();

return ctx.next();

Again, awaiting ctx.next() adds no value.

iuioiua · 2025-10-20T21:32:08Z

packages/fresh/src/middlewares/ip_restriction.ts

+    }
+
+    if ((rules.allowList || []).length === 0) {
+      return await ctx.next();


Suggested change

return await ctx.next();

return ctx.next();

Ditto

iuioiua · 2025-10-20T21:32:48Z

packages/fresh/src/middlewares/ip_restriction.ts

+      return await ctx.next();
+    } else {
+      if (options?.onError) {
+        return await options.onError({ addr, type }, ctx);


Suggested change

return await options.onError({ addr, type }, ctx);

return options.onError({ addr, type }, ctx);

Ditto

iuioiua · 2025-10-20T21:36:10Z

packages/fresh/src/middlewares/ip_restriction.ts

+): Middleware<State> {
+  return async function ipRestriction<State>(ctx: Context<State>) {


Suggested change

): Middleware<State> {

return async function ipRestriction<State>(ctx: Context<State>) {

): Middleware<State> {

const onBlock = options.onError ?? () => new Response("Forbidden", { status: 403 });

return async function ipRestriction<State>(ctx: Context<State>) {

Reminder: avoids having to write if (options?.onError) blocks and makes things clear more immediately.

iuioiua · 2025-10-20T21:48:26Z

packages/fresh/src/middlewares/ip_filter.ts

+      if (options?.onError) {
+        return options.onError({ addr, type }, ctx);
+      }
+      return blockError();


Ditto. See comment about onError being defined within the exported function.

iuioiua · 2025-10-20T21:49:08Z

packages/fresh/src/middlewares/ip_filter.ts

+      if (options?.onError) {
+        return await options.onError({ addr, type }, ctx);
+      }


Ditto. See comment about onError being defined within the exported function.

iuioiua · 2025-10-20T21:50:32Z

packages/fresh/src/middlewares/ip_filter.ts

+/**
+ * IP restriction Middleware for Fresh.
+ *
+ * @param rules rules `{ denyList: string[], allowList: string[] }`.


Suggested change

* @param rules rules `{ denyList: string[], allowList: string[] }`.

* @param rules Deny and allow rules object.

How you had it isn't how @param JSDoc tags should be written. They need to be written in natural human language describing what the variable is.

iuioiua · 2025-10-20T21:51:11Z

packages/fresh/src/middlewares/ip_restriction.ts

+ * ```ts
+ * const app = new App<State>()
+ *
+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}))


Suggested change

* app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}))

* app.use(ipRestriction({

* denyList: ["192.168.1.10", "2001:db8::1"],

* }));

Nit

iuioiua · 2025-10-20T21:52:09Z

packages/fresh/src/middlewares/ip_restriction.ts

+ *     return new Response("custom onError", { status: 401 });
+ *   },
+ * };
+ * app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))


Suggested change

* app.use(ipRestriction({denyList: ["192.168.1.10", "2001:db8::1"]}, customOnError))

* app.use(ipRestriction({

* denyList: ["192.168.1.10", "2001:db8::1"]

* }, customOnError));

Nit

iuioiua

Getting closer.

iuioiua · 2025-10-21T21:18:29Z

deno.lock

Should these changes be reverted?

I think ip_filter is necessary because it relies on @std/net.

iuioiua · 2025-10-21T21:24:16Z

packages/fresh/src/middlewares/ip_filter.ts

+export interface ipFilterOptions {
+  onError?: <State>(
+    remote: {
+      addr: string;
+      type: Deno.NetworkInterfaceInfo["family"] | undefined;
+    },
+    ctx: Context<State>,
+  ) => Response | Promise<Response>;
+}


This interface and its properties need documentation.

We have addressed this matter.

iuioiua · 2025-10-21T21:26:13Z

packages/fresh/src/middlewares/ip_filter.ts

+    }
+
+    const addr = ctx.info.remoteAddr.hostname;
+    const type = findType(addr);


I think whether you're using addr and type is unrelated to my point 😛

See my suggestion below.

iuioiua · 2025-10-21T21:34:43Z

packages/fresh/src/middlewares/ip_filter.ts

+    }
+
+    const addr = ctx.info.remoteAddr.hostname;
+    const type = findType(addr);


Suggested change

const type = findType(addr);

const type = IPv4(addr) ? "IPv4" : "IPv6";

I seem to have been overthinking it unnecessarily. I would like to adopt your proposal.

iuioiua · 2025-10-21T21:37:36Z

packages/fresh/src/middlewares/ip_filter.ts

+    if (type == undefined) {
+      return blockError();
+    }


Yes, I do think it's unnecessary because type can only ever be IPv4 or IPv6.

iuioiua · 2025-10-21T21:42:47Z

packages/fresh/src/middlewares/ip_filter.ts

+      throw new TypeError(
+        "Unsupported transport protocol. TCP & UDP is supported.",
+      );


Suggested change

throw new TypeError(

"Unsupported transport protocol. TCP & UDP is supported.",

);

return ctx.next();

iuioiua · 2025-10-21T21:44:10Z

packages/fresh/src/middlewares/ip_filter.ts

+    if (
+      ctx.info.remoteAddr.transport !== "udp" &&
+      ctx.info.remoteAddr.transport !== "tcp"
+    ) {
+      throw new TypeError(
+        "Unsupported transport protocol. TCP & UDP is supported.",
+      );
+    }


Sorry, to correct my stance, yes, we should return early if not UDP or TCP traffic, because an IP address isn't being used. But I don't think throwing is the correct behaviour. Instead, we should just pass through. See my suggestion above.

iuioiua · 2025-10-21T21:49:12Z

packages/fresh/src/middlewares/ip_filter.ts

+  rules: IpFilterRules,
+  options?: ipFilterOptions,
+): Middleware<State> {
+  const onBlock = options?.onError ?? (() => blockError());


Suggested change

const onBlock = options?.onError ?? (() => blockError());

const onBlock = options?.onError ?? (() => new Response("Forbidden", { status: 403 }));

So the reader doesn't have to scroll back up to see what onBlock does by default (since it's simple anyway).

iuioiua · 2025-10-21T21:52:40Z

packages/fresh/src/middlewares/ip_filter.ts

+    if ((rules.allowList || []).length === 0) {
+      return ctx.next();
+    } else {
+      return onBlock({ addr, type }, ctx);


Suggested change

if ((rules.allowList || []).length === 0) {

return ctx.next();

} else {

return onBlock({ addr, type }, ctx);

return onBlock({ addr, type }, ctx);

I believe this first if statement is already covered by the preceding allow block.

this section is needs.

This is because there were cases where the permission list was not explicitly set.
However, as pointed out, some parts seemed unnecessary, so I have reorganized the content.

Thank you

iuioiua · 2025-10-21T21:55:20Z

packages/fresh/src/middlewares/ip_filter.ts

+}
+
+/**
+ * IP restriction Middleware for Fresh.


You should explain this filter. I.e. the precedence of rules. So deny rules take precedence over allow rules and traffic not matching any rule is denied by default (implicit deny).

I mentioned this matter.

Thankyou

iuioiua

LGTM 👍🏾

Octo8080X · 2026-01-24T07:20:06Z

@marvinhagemeister

Thank you for the review on this PR a while back. It’s been about two months since iuioiua-san kindly provided feedback, and I truly appreciate the support. Please let me know if there is anything additional I can do to help get this merged—I'm ready to jump back in and make any necessary updates immediately.

Octo8080X added 7 commits June 14, 2025 13:48

Refactor IP restriction middleware: clean up debug logs and improve flow

571b272

Remove unnecessary comments and console.log statements from IP restri…

194b59e

…ction middleware

Remove unnecessary comments and console.log statements from IP restri…

8362db1

…ction tests

Update exports in mod.ts for ipRestriction and related types

167feba

Export IPRestrictionRules type from ip_restriction in mod.ts

7ae6fc3

Rename test file to ip_restriction_test.ts for consistency with sourc…

0eb73c3

…e file naming

Export getIP from ip_restriction in mod.ts for middleware completeness

72ae3bd

iuioiua suggested changes Jun 14, 2025

View reviewed changes

Octo8080X and others added 9 commits June 14, 2025 19:26

Fix ipRestriction middleware tests and improve coverage

5987fc8

Export IPRestrictionRules type from ip_restriction module

2e93114

Merge branch 'main' into feature/add_ip_restriction_middleware

2deeb7c

Merge branch 'main' into feature/add_ip_restriction_middleware

25c2cdb

update

4e5ae78

use @std/net

caae853

update export

9db23e6

update docs

c93fd79

Merge branch 'main' into feature/add_ip_restriction_middleware

8e79b17

Octo8080X requested review from iuioiua and marvinhagemeister October 8, 2025 12:52

Merge branch 'main' into feature/add_ip_restriction_middleware

bc7f51e

iuioiua suggested changes Oct 14, 2025

View reviewed changes

Octo8080X added 4 commits October 21, 2025 00:43

fix

53612b9

Merge branch 'feature/add_ip_restriction_middleware' of github.com:Oc…

2645569

…to8080X/fresh into feature/add_ip_restriction_middleware

fix

abd6665

fix

f14e7dc

iuioiua suggested changes Oct 20, 2025

View reviewed changes

Octo8080X and others added 3 commits October 21, 2025 21:23

rename and fix

1468cde

Merge branch 'main' into feature/add_ip_restriction_middleware

e37ad41

fix

25d5d2d

Octo8080X and others added 4 commits October 21, 2025 21:27

fix

dfe28d4

fix

a7ab3de

fix

df3b5da

Merge branch 'main' into feature/add_ip_restriction_middleware

c22c4bf

iuioiua reviewed Oct 21, 2025

View reviewed changes

Octo8080X and others added 12 commits November 11, 2025 23:28

Merge branch 'main' into feature/add_ip_restriction_middleware

7236b07

merge main

3f3d37d

fix

007e150

add document

4b15afe

organized method

4c2f7a6

Merge branch 'denoland:main' into feature/add_ip_restriction_middleware

9ef84c7

logic update

5383f74

logic update

75805b8

logic update

f50aa69

logic update

5e2be56

update coments

ab623c8

restore lockfile

34407e8

Octo8080X requested a review from iuioiua November 22, 2025 14:02

iuioiua approved these changes Nov 23, 2025

View reviewed changes

Octo8080X and others added 3 commits December 23, 2025 23:45

Merge branch 'main' into feature/add_ip_restriction_middleware

ef5ff80

Merge branch 'main' into feature/add_ip_restriction_middleware

4328d63

add @std/net

4e16d46

	* @example custom error handling
	* @example Custom error handling


		const denyMatcher = buildMatcher(denyList);
		const allowMatcher = buildMatcher(allowList);

+  const onError = options?.onError ?? (() =>
+    new Response("Forbidden", {
+      status: 403,
+      headers: {
+        "Content-Type": "text/plain",
+      },
+    }));

	return await options.onError({ addr, type }, ctx);
	return options.onError({ addr, type }, ctx);

		): Middleware<State> {
		return async function ipRestriction<State>(ctx: Context<State>) {

	* @param rules rules `{ denyList: string[], allowList: string[] }`.
	* @param rules Deny and allow rules object.

	const type = findType(addr);
	const type = IPv4(addr) ? "IPv4" : "IPv6";

	const onBlock = options?.onError ?? (() => blockError());
	const onBlock = options?.onError ?? (() => new Response("Forbidden", { status: 403 }));

Conversation

Octo8080X commented Jun 14, 2025

Why was this PR initiated?

What does this PR do?

Uh oh!

iuioiua left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Octo8080X Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Octo8080X commented Oct 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iuioiua left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iuioiua left a comment

Choose a reason for hiding this comment

Octo8080X Jun 14, 2025 •

edited

Loading